External Parameterization

When content is loaded directly, either through URL loading or through iframe embedding, it is often convenient to allow users to change the targeted item's values using external input (by adding filters to the URL's query string). This process is known as external parameterization.

Note: External parameterization should not be confused with the internal parameterization capabilities. Although they're related, their functionality is separate.

General Syntax

All items that are fed into the platform for parameterization need to follow the general syntax for an item's unique name.

[dimension].[hierarchy].[member name]

• The dimension is usually the table name.
• The hierarchy is usually the column name.
• The member name is usually the item's caption or visible name.

Note: MDX syntax will usually provide the exact and compliant syntax for a member in a style similar to this formulation, but not necessarily identical.

Direct URL Loading

Click Copy Link from an item's app menu, or from its Actions Panel in the Content Explorer. The item's link will be copied to clipboard, and can then be shared with others and pasted in the browser, and filters can be added to the URL.

When parameterizing a URL for direct loading of content, the formulation is as follows:

&filter={unique member name}

The unique member name is NOT case sensitive.

Multiple filters (including multiple selections from the same hierarchy) can be chained into the URL using the "&" character, as follows:

{YourPyramidsite}/direct/?id={content identifier}
&filter=[date].[year].[2009]&filter=[date].[year].[2008]
&filter=[customer].[country].[australia]

Filtering with PQL Expressions

Pyramid supports using PQL functions in URL parameters. This example initializes a discovery for a selected date range (December 30^th 2010 to December 31^st 2010) on launch. Date range parameters (defined using PQL) are passed to the target as part of the URL:

https://eg.pyramdanalytics.com/direct/?id=direct?id=134fd567-d6e3-4b8e-9484-b720d4e39a17
&filter=%7B[data].[dateKey]:SET:%7BRANGE(DateSelection([data].[dateKey],"2010-12-30",5),DateSelection([data].[dateKey],"2010-12-31",5))%7D%7D

It is important to note that the {braces} that are required to define this range need to be escaped for use.

• Click here for more about URL parameterization

Filtering using Targets

If your URL points to a presentation, you need to change from the &filter shown above to the &target approach. The target approach allows users to inject parameters into a multi-visual dashboard and then direct the parameter to the correct item or items on a the relevant slides.

• Click here for more about Target Parameterization

Embedded Content

Embedded content can also be parameterized through JavaScript. The formulation is represented as follows:

type ExternalParameters = {
  reportFilters: {
    value: string
  }[ ]
}

More specifically, the syntax is:

var myParams = {
	reportFilters: [
		{value:  "{member unique name 1}"}, 
		{value:  "{member unique name x}"}
		]
}

Below is an example:

var params = {
  reportFilters: [{
    value:  "[Customer].[Country].[United States]"
  }, 
  {
    value:  "[Date].[year].[2010]"
  }]
}

To see how this can be used in a full embedding example, click here.